.TH std::tuple 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::tuple \- std::tuple

.SH Synopsis
   Defined in header <tuple>
   template< class... Types >  \fI(since C++11)\fP
   class tuple;

   Class template std::tuple is a fixed-size collection of heterogeneous values. It is
   a generalization of std::pair.

   If std::is_trivially_destructible<Ti>::value is true for every Ti in Types, the
   destructor of std::tuple is trivial.

   If a program declares an explicit or partial specialization of std::tuple, the
   program is ill-formed, no diagnostic required.

.SH Template parameters

   Types... - the types of the elements that the tuple stores. Empty list is supported.

.SH Member functions

   constructor   constructs a new tuple
                 \fI(public member function)\fP
   operator=     assigns the contents of one tuple to another
                 \fI(public member function)\fP
   swap          swaps the contents of two tuples
                 \fI(public member function)\fP

.SH Non-member functions

   make_tuple            creates a tuple object of the type defined by the argument
   \fI(C++11)\fP               types
                         \fI(function template)\fP
   tie                   creates a tuple of lvalue references or unpacks a tuple into
   \fI(C++11)\fP               individual objects
                         \fI(function template)\fP
   forward_as_tuple      creates a tuple of forwarding references
   \fI(C++11)\fP               \fI(function template)\fP
   tuple_cat             creates a tuple by concatenating any number of tuples
   \fI(C++11)\fP               \fI(function template)\fP
   get(std::tuple)       tuple accesses specified element
   \fI(C++11)\fP               \fI(function template)\fP
   operator==
   operator!=
   operator<
   operator<=
   operator>
   operator>=            lexicographically compares the values in the tuple
   operator<=>           \fI(function template)\fP
   (removed in C++20)
   (removed in C++20)
   (removed in C++20)
   (removed in C++20)
   (removed in C++20)
   (C++20)
   std::swap(std::tuple) specializes the std::swap algorithm
   \fI(C++11)\fP               \fI(function template)\fP

   Helper concepts

   tuple-like specifies that a type implemented the tuple protocol
   pair-like  (std::get, std::tuple_element, std::tuple_size)
   (C++23)    (exposition-only concept*)

.SH Helper classes

   std::tuple_size<std::tuple>             obtains the size of tuple at compile time
   \fI(C++11)\fP                                 \fI(class template specialization)\fP
   std::tuple_element<std::tuple>          obtains the type of the specified element
   \fI(C++11)\fP                                 \fI(class template specialization)\fP
   std::uses_allocator<std::tuple>         specializes the std::uses_allocator type
   \fI(C++11)\fP                                 trait
                                           \fI(class template specialization)\fP
   std::basic_common_reference<tuple-like> determines the common reference type of a
   (C++23)                                 tuple and a tuple-like type
                                           \fI(class template specialization)\fP
   std::common_type<tuple-like>            determines the common type of a tuple and a
   (C++23)                                 tuple-like type
                                           \fI(class template specialization)\fP
   std::formatter<std::tuple>              formatting support for tuple
   (C++23)                                 \fI(class template specialization)\fP
   ignore                                  placeholder to skip an element when
   \fI(C++11)\fP                                 unpacking a tuple using tie
                                           (constant)

   Deduction guides \fI(since C++17)\fP

.SH Notes

   Since the "shape" of a tuple – its size, the types of its elements, and the ordering
   of those types – are part of its type signature, they must all be available at
   compile time and can only depend on other compile-time information. This means that
   many conditional operations on tuples – in particular, conditional prepend/append
   and filter – are only possible if the conditions can be evaluated at compile time.
   For example, given a std::tuple<int, double, int>, it is possible to filter on types
   – e.g. returning a std::tuple<int, int> – but not to filter on whether or not each
   element is positive (which would have a different type signature depending on
   runtime values of the tuple), unless all the elements were themselves constexpr.

   As a workaround, one can work with tuples of std::optional, but there is still no
   way to adjust the size based on runtime information.

   Until N4387 (applied as a defect report for C++11), a function could not return a
   tuple using copy-list-initialization:

 std::tuple<int, int> foo_tuple()
 {
     return {1, -1};  // Error until N4387
     return std::tuple<int, int>{1, -1}; // Always works
     return std::make_tuple(1, -1); // Always works
 }

.SH Example


// Run this code

 #include <iostream>
 #include <stdexcept>
 #include <string>
 #include <tuple>

 std::tuple<double, char, std::string> get_student(int id)
 {
     switch (id)
     {
         case 0: return {3.8, 'A', "Lisa Simpson"};
         case 1: return {2.9, 'C', "Milhouse Van Houten"};
         case 2: return {1.7, 'D', "Ralph Wiggum"};
         case 3: return {0.6, 'F', "Bart Simpson"};
     }

     throw std::invalid_argument("id");
 }

 int main()
 {
     const auto student0 = get_student(0);
     std::cout << "ID: 0, "
               << "GPA: " << std::get<0>(student0) << ", "
               << "grade: " << std::get<1>(student0) << ", "
               << "name: " << std::get<2>(student0) << '\\n';

     const auto student1 = get_student(1);
     std::cout << "ID: 1, "
               << "GPA: " << std::get<double>(student1) << ", "
               << "grade: " << std::get<char>(student1) << ", "
               << "name: " << std::get<std::string>(student1) << '\\n';

     double gpa2;
     char grade2;
     std::string name2;
     std::tie(gpa2, grade2, name2) = get_student(2);
     std::cout << "ID: 2, "
               << "GPA: " << gpa2 << ", "
               << "grade: " << grade2 << ", "
               << "name: " << name2 << '\\n';

     // C++17 structured binding:
     const auto [gpa3, grade3, name3] = get_student(3);
     std::cout << "ID: 3, "
               << "GPA: " << gpa3 << ", "
               << "grade: " << grade3 << ", "
               << "name: " << name3 << '\\n';
 }

.SH Output:

 ID: 0, GPA: 3.8, grade: A, name: Lisa Simpson
 ID: 1, GPA: 2.9, grade: C, name: Milhouse Van Houten
 ID: 2, GPA: 1.7, grade: D, name: Ralph Wiggum
 ID: 3, GPA: 0.6, grade: F, name: Bart Simpson

   Defect reports

   The following behavior-changing defect reports were applied retroactively to
   previously published C++ standards.

      DR    Applied to         Behavior as published              Correct behavior
   LWG 2796 C++11      triviality of the destructor of        specified
                       std::tuple was unspecified
                                                              the program is ill-formed
   LWG 3990 C++11      a program could declare an explicit or in this
                       partial specialization of std::tuple   case (no diagnostic
                                                              required)

.SH References

     * C++23 standard (ISO/IEC 14882:2023):

     * 22.4 Tuples [tuple]
     * C++20 standard (ISO/IEC 14882:2020):

     * 20.5 Tuples [tuple]
     * C++17 standard (ISO/IEC 14882:2017):

     * 23.5 Tuples [tuple]
     * C++14 standard (ISO/IEC 14882:2014):

     * 20.4 Tuples [tuple]
     * C++11 standard (ISO/IEC 14882:2011):

     * 20.4 Tuples [tuple]

.SH See also

   pair implements binary tuple, i.e. a pair of values
        \fI(class template)\fP
